.TH E1432_SET_SPAN 3 E1432
.SH NAME
.nf
e1432_set_span \- Set measurement span
e1432_get_span \- Get measurement span
.fi
.IX e1432_set_span(3) 3
.IX e1432_get_span(3) 3
.SH SYNOPSIS
.cS
SHORTSIZ16 e1432_set_span(E1432ID hw, SHORTSIZ16 ID, FLOATSIZ32 span)
SHORTSIZ16 e1432_get_span(E1432ID hw, SHORTSIZ16 ID, FLOATSIZ32 *span)
.cE
.SH DESCRIPTION

\fIe1432_set_span\fR sets the measurement bandwidth.  For an input
channel, the span specifies the maximum frequency at which valid
alias-protected data will be received (frequencies above that are
filtered out).  For a source channel, the span specifies the maximum
frequency at which the output signal will correctly track the signal
that the source is attempting to generate.

The valid values for \fIspan\fR depend of the current clock frequency,
which is set by \fIe1432_set_clock_freq\fR.  The clock frequency
should be set before setting the span.  Normally, the maximum valid
span is max_span = clock_freq/2.56.  Valid spans are max_span divided
by powers of two, and max_span divided by five and by powers of two.
The ratio between the span and the max_span is called the decimation
factor.

\fBNOTE:\fR  When in order tracking the max_span = clock_freq / 5.12, since
the order tracking algorithm uses data oversampled by two.  Also in the order
tracking mode, twice as much data is passed from the input SCAs to the
main processor. The outputs of all of the decimation filters in the 
input SCAs are output for the order tracking algorithm to use.  This
increased data load forces a restriction on the number of channels that
can be used at the top order tracking spans ... only two SCA may be active
on some of the top spans.
In the E1432 this means only 8 channels residing on two SCAs may be active
at the top span (10Khz at clock frequency of 51200).
In the E1433 only 4 channels residing on two SCAs may be active above at
span of 10Khz.  Any more active channels will cause the error, 
\fBERR1432_ILLEGAL_ORDER_CHANNEL_COMBO\fR.

For the E1432 51.2 kHz input SCA, the maximum number of
decimate-by-two passes allowed is nine, so the maximum decimation
factor is 5*2^9 and the minimum valid span is clock_freq/(2.56*5*2^9).
If the clock frequency is larger than 51.2 kHz, then the E1432 input
channel is unable to do a decimation factor of one; the minimum
decimation factor is 2 and the maximum valid span is clock_freq/5.12.

For the E1433 196 kHz input SCA, the maximum number of decimate-by-two
passes allowed is 17, so the maximum decimation factor is 5*2^17.

Due to limits in the E1433A DSP processors, when the clock frequency is set
higher than 128000 Hz, the E1432 input SCA is unable to do \fIany\fR
decimation, so in this case the \fIonly\fR valid span is
clock_freq/2.56.  Attempts to use decimation when the clock frequency
is above 128000 Hz will result in an error when the measurement starts.
This limitation does not apply to the E1433B.

For the E1434 source, and the option 1D4 source board, the maximum
number of decimate-by-two passes allowed is 16, so the maximum
decimation factor is 5*2^16.

The effective sample rate, which is the rate at which data is received
from an input or used by a source, is normally equal to 2.56 times the
span.  If the data is oversampled (see
\fIe1432_set_decimation_oversample\fR), then the effective sample rate
is 5.12 times the span.

In certain cases, some of the frequencies above the maximum span may
still contain valid alias-protected data.  This will be the case if
the digital filters in an SCA have a sharper cutoff than the usual
1/2.56.  This is the case with both the E1432 51.2 kHz input SCA and
the E1433 196 kHz input SCA when at top span.  The E1432 and E1433 top
span filter cutoff is clock_freq/2.226 (23 kHz when the clock
frequency is 51.2 kHz, 88.3 kHz when the clock frequency is 196.608
kHz).  However, this e1432_set_span function ignores the extra
bandwidth, and pretends that the maximum span is always 1/2.56 times
the effective sample rate.

\fBNOTE:\fR There are further restrictions on allowable spans when in zoom mode.
These are documented in the \fIe1432_set_zoom\fR function.

\fIe1432_get_span\fR returns the current span in Hertz.  All channels
of a module have the same span.

This parameter is a "global" parameter.  It applies to an entire E1432
module rather than to one of its channels.  The \fIID\fR parameter is
used only to identify which module the function applies to, and all
channels in that module will report the same value for this parameter.

\fIhw\fR must be the result of a successful call to
\fIe1432_assign_channel_numbers\fR, and specifies the group of
hardware to talk to.

\fIID\fR is either the ID of a group of channels that was obtained with a
call to \fIe1432_create_channel_group\fR, or the ID of a single
channel.

\fIspan\fR is the desired span, in Hz.  It is rounded up to the next
larger valid span.

The algorithm to pick what "valid" span to round to is different
depending on whether a measurement is currently running or not.  If no
measurement is running, the span is chosen from all valid spans.

If a measurement is running, the span is required to use the same
"divide by five" setting that the original span used when the
measurement was started.  For example, if the clock frequency is 51200
Hz, it is valid to switch from 5000 Hz to 10000 Hz spans when a
measurement is running, but it is not valid to switch from 4000 Hz to
10000 Hz.  The 4000 Hz span uses divide by five, while the 10000 Hz
span does not.

Because the algorithm for rounding the span depends on whether a
measurement is running, and is somewhat complicated anyway, it is
generally a good idea to call \fIe1432_get_span\fR after setting the
span.  This will ensure that the host application knows the actual
span that the module is using.

If the span is changed while a measurement is running, the module will
flush any data from before the span change.  All data read from the
module after the span change will be data at the new span.  When using
trailer data (see \fIe1432_set_append_status\fR), the "gap" field in
the trailer will not be exactly correct for the first block after the
span change.

.SH "RESET VALUE"
After a reset, each module is set to the maximum legal span.
.SH "RETURN VALUE"
Return 0 if successful, a (negative) error number otherwise.
.SH "SEE ALSO"
.na
e1432_set_clock_freq, e1432_get_span_limits, e1432_set_center_freq
.ad
